Document all the available Testcontainers integrations #44187

thecooldrop · 2025-02-09T21:36:54Z

In this PR I have documented the ways in which containers provided by Testcontainers framework can be incorporated into the test tests managed by Spring's TestContext Framework.

In addition to describing how to use the containers, information on lifecycle of containers during tests has been added.

eddumelendez

This clarification is great! I've left some comments that could help.

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

eddumelendez · 2025-02-11T18:28:14Z

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

+== Using via Spring managed beans
+
+The containers provided by Testcontainers framework can be managed by Spring Boot as beans.
+This method is often used in combination with javadoc:org.springframework.boot.testcontainers.service.connection.ServiceConnection[format=annotation].


@ServiceConnection can be used with static fields and beans.

I do not quite understand what you mean with that, in context of the code which is selected here in comment. Is it that the sentence "This method is often used in combination with..." seems to point that it is the only combination in which @ServiceConnection annotation is used?

So I rephrased the sentence so that it is clearer that this is not the only option. I hope now it is satisfactory. If not feel free to continue the discussion.

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

eddumelendez · 2025-02-11T18:30:10Z

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

+
+== Using via importing container declaration classes
+
+A common pattern with Testcontainers framework is to declare the Container instances as static fields in an interface


IMO, it should highlight that this enables reusability of container configuration.

We can do that. I partially disagree though. As I am reading through rest of the Spring documentation I note that it is focused solely on documenting on which features are offered by Spring, and does not repeat or clarify software development "best practices". I followed this style here.

Added as tip

eddumelendez · 2025-02-11T18:31:01Z

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

+== Lifecycle of managed containers
+
+If you have used the annotations and extensions provided by Testcontainers framework, then the lifecycle of container instances is managed by the Testcontainers framework.
+Please refer to the official documentation for the information about lifecycle of the containers, when managed by the Testcontainers framework.


Add Link to the official docs maybe

Does Antora offer broken link checks? If so I will gladly add the link. I was cautious about inclusion of links, because links change and that can be irritating for the readers.

Added as Antora attribute.

eddumelendez · 2025-02-11T18:32:24Z

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

+
+The test containers can be started multiple times.
+Like any other beans the test containers are created and started once per application context managed by the TestContext Framework.
+For details about how TestContext framework manages the underlying application contexts and beans therein, please refer to the official Spring documentation.


should add link?

I assume that here you are refering to link to TestContext Framework docs.

Added reference to Spring docs, without deep linking to TestContext framework.

eddumelendez · 2025-02-11T18:34:29Z

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

+The container beans are stopped after the destruction of beans of other types.
+This ensures that any beans depending on the functionalities provided by the containers are cleaned up first.
+
+The containers are stopped as part of the application shutdown process, managed by the TestContext framework.


This part is important to highlight. In some cases, for example, using activemq, kafka, pulsar and other containers, I recommend to declare it as a beans rather than static fields because that way the application context will shutdown the client first and then the container. Otherwise, when the container shutdown first the client will throw some errors because connection has been lost.

I understand that you would like to have a concrete example in addition to the general explanation already provided, so that the readers can more clearly understand the "why" behind usage. Is my understanding correct?

Added as tips and notes.

tips and notes are great! my examples were only to provide an explanation about the issue en general. 👍🏽

thecooldrop · 2025-02-16T08:07:54Z

@eddumelendez Ready for re-review.

eddumelendez

left additional comments. LGTM, in general. Thanks again!

eddumelendez · 2025-02-18T15:55:20Z

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

+== Using via @Testcontainers JUnit5 extension
+
+The Testcontainers provides JUnit5 extensions, which can be used to manage containers in your tests.
+The extension is activated by applying the


This is incomplete

Wierd that I missed that, given that I know exactly what my thoughts were here. I will fill this up.

Okay so I corrected this and completerd the sentence.

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

eddumelendez · 2025-02-18T16:06:21Z

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

+The container beans are stopped after the destruction of beans of other types.
+This ensures that any beans depending on the functionalities provided by the containers are cleaned up first.
+
+The containers are stopped as part of the application shutdown process, managed by the TestContext framework.


tips and notes are great! my examples were only to provide an explanation about the issue en general. 👍🏽

In this commit I have documented three methods of starting containers from Testcontainer library as part of the Spring Boot tests. Signed-off-by: Vanio Begic <[email protected]>

Signed-off-by: Vanio Begic <[email protected]>

Closes spring-projects#43738 Signed-off-by: Vanio Begic <[email protected]>

Signed-off-by: Vanio Begic <[email protected]>

Concretely I have ensured that there are three lines between text and next header. Also I added anchors to each header Signed-off-by: Vanio Begic <[email protected]>

Signed-off-by: Vanio Begic <[email protected]>

thecooldrop · 2025-02-22T22:15:29Z

@eddumelendez I think we should be good to go now 🤞

eddumelendez · 2025-02-26T15:56:29Z

...project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

+The test containers can be started multiple times.
+Like any other beans the test containers are created and started once per application context managed by the TestContext Framework.


I think this can be just containers instead of test containers.

eddumelendez

Looks great! thanks!

spring-projects-issues added the status: waiting-for-triage An issue we've not yet triaged label Feb 9, 2025

snicoll changed the title ~~Add documentation on different ways of using test containers with Spring and information about lifecycle of containers (#43738)~~ Document all the available Testcontainers integrations Feb 10, 2025

snicoll added type: documentation A documentation update and removed status: waiting-for-triage An issue we've not yet triaged labels Feb 10, 2025

snicoll added this to the 3.3.x milestone Feb 10, 2025

snicoll mentioned this pull request Feb 10, 2025

Add dedicated section for registering a container as a bean in the Testcontainers section #43738

Closed

eddumelendez reviewed Feb 11, 2025

View reviewed changes

thecooldrop force-pushed the gh-43738 branch from 38c227f to bd96459 Compare February 16, 2025 07:35

thecooldrop force-pushed the gh-43738 branch from 8398340 to 092e4ca Compare February 16, 2025 08:31

snicoll requested a review from eddumelendez February 18, 2025 10:26

eddumelendez reviewed Feb 18, 2025

View reviewed changes

thecooldrop added 7 commits February 22, 2025 23:14

Document methods of starting Testcontainer containers

4e2bd93

In this commit I have documented three methods of starting containers from Testcontainer library as part of the Spring Boot tests. Signed-off-by: Vanio Begic <[email protected]>

Add information about lifecycle of testcontainers to documentation

64d82a5

Signed-off-by: Vanio Begic <[email protected]>

Fix formatting and add necessary suppressions

b50570f

Closes spring-projects#43738 Signed-off-by: Vanio Begic <[email protected]>

Replace 'Testcontainers framework' with just 'Testcontainers'

668e136

Signed-off-by: Vanio Begic <[email protected]>

Improve wording and add tips and notes where appropriate

af345d3

Signed-off-by: Vanio Begic <[email protected]>

Improve formatting according to the requirements in Wiki

b865216

Concretely I have ensured that there are three lines between text and next header. Also I added anchors to each header Signed-off-by: Vanio Begic <[email protected]>

Complete the omitted sentence

92efef4

Signed-off-by: Vanio Begic <[email protected]>

thecooldrop force-pushed the gh-43738 branch from 0d6ff97 to 92efef4 Compare February 22, 2025 22:14

eddumelendez reviewed Feb 26, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document all the available Testcontainers integrations #44187

Document all the available Testcontainers integrations #44187

thecooldrop commented Feb 9, 2025

eddumelendez left a comment

eddumelendez Feb 11, 2025

thecooldrop Feb 12, 2025

thecooldrop Feb 16, 2025

eddumelendez Feb 11, 2025

thecooldrop Feb 12, 2025

thecooldrop Feb 16, 2025

eddumelendez Feb 11, 2025

thecooldrop Feb 12, 2025 •

edited

Loading

thecooldrop Feb 16, 2025

eddumelendez Feb 11, 2025

thecooldrop Feb 12, 2025

thecooldrop Feb 16, 2025 •

edited

Loading

eddumelendez Feb 11, 2025 •

edited

Loading

thecooldrop Feb 12, 2025

thecooldrop Feb 16, 2025

eddumelendez Feb 18, 2025

thecooldrop commented Feb 16, 2025

eddumelendez left a comment

eddumelendez Feb 18, 2025

thecooldrop Feb 21, 2025

thecooldrop Feb 22, 2025

eddumelendez Feb 18, 2025

thecooldrop commented Feb 22, 2025 •

edited

Loading

eddumelendez Feb 26, 2025

eddumelendez left a comment


		== Using via importing container declaration classes

		A common pattern with Testcontainers framework is to declare the Container instances as static fields in an interface

		The test containers can be started multiple times.
		Like any other beans the test containers are created and started once per application context managed by the TestContext Framework.

Document all the available Testcontainers integrations #44187

Are you sure you want to change the base?

Document all the available Testcontainers integrations #44187

Conversation

thecooldrop commented Feb 9, 2025

eddumelendez left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thecooldrop Feb 12, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thecooldrop Feb 16, 2025 • edited Loading

Choose a reason for hiding this comment

eddumelendez Feb 11, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thecooldrop commented Feb 16, 2025

eddumelendez left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thecooldrop commented Feb 22, 2025 • edited Loading

Choose a reason for hiding this comment

eddumelendez left a comment

Choose a reason for hiding this comment

thecooldrop Feb 12, 2025 •

edited

Loading

thecooldrop Feb 16, 2025 •

edited

Loading

eddumelendez Feb 11, 2025 •

edited

Loading

thecooldrop commented Feb 22, 2025 •

edited

Loading